Documentation for class collection

Inherits from 	basic_object 

Properties declared in collection 

Class Methods declared in collection 

Methods declared in collection 
	any 
		add_first(object) 
		add_last(object) 
		as_string 
		at(index) 
		average 
		bubble_sort 
		duplicate 
		duplicate_shallow 
		empty 
		first 
		generic_sort(message) 
		includes(element) 
		index_of(element) 
		insert(element, index) 
		inspect 
		is_empty 
		is_equal_to(object) 
		last 
		max 
		min 
		quick_sort 
		remove_at(index) 
		remove_duplicates 
		remove_first 
		remove_last 
		rename(name) 
		replace(old_element, new_element) 
		replace_all(old_element, new_element) 
		replace_at(index, new_element) 
		reverse 
		size 
		sort 
		summate 
	remove 
		remove_at(index) 
		remove_duplicates 
		remove_first 
		remove_last 
	replace 
		replace(old_element, new_element) 
		replace_all(old_element, new_element) 
		replace_at(index, new_element) 

Class 
#begin_class
collection 
The class collection is a sub-class of the class basic_object. 
Collections are used to store objects. A collection is an ordered list of objects. 
The syntax of a collection that contains the first five integers would be:

[1 2 3 4 5]

i.e. a left square bracket ([) followed by the objects delimited by a space followed by a right square bracket (]).
Other examples of collections are:

["a" "collection" "of" "strings"]
[{image 17} {image 18} {image 19}]

Note that collections may contain objects of any class, even other collections.

The collection
[12 "abc" {button 14} {window} [1 2 3]]
includes an integer, a string, a button object, the window class and another collection.

A collection can even include itself.
Ex:
c := [1 2 3 4 5]
returns [1 2 3 4 5]
c:add_last(c)
returns [1 2 3 4 5 ...]
The ellipsis (...) represents the collection itself when printed. A collection that includes itself is called a circular collection.
#end_class

Properties 

Methods 

#begin_method
add_first(object) 
Adds object first in the collection.
Returns self.
Ex:
c := [1 2 3 4]
c:add_first(5)
returns [5 1 2 3 4]
#end_method

#begin_method
add_last(object) 
Adds object last in the collection.
Returns self.
Ex:
c := [1 2 3 4]
c:add_last(5)
returns [1 2 3 4 5]
#end_method

#begin_method
as_string 
Returns a string object which is created by concatenating all the elements in the collection.
Ex:
c := [1 2 "three" {window}]
c:as_string
returns "12threewindow"
#end_method

#begin_method
at(index) 
Returns the object at the position index in the collection. If index is higher than the number of elements in the collection the method returns nil.
Note: The first element in a collection has the index 1.
Ex:
c := [1 2 "three" "four"]
c:at(1)
returns 1
c:at(3)
returns "three"
c:at(5)
returns nil
#end_method

#begin_method
average 
Returns the average of all the elements in the collection.
Note: The elements in the collection must be numbers.
#end_method

#begin_method
bubble_sort 
Sorts the collection using the bubble-sort algorithm. 
Returns self.
Note: The elements should all be of the same type, for example numbers or strings or characters.
Ex:
c := [4 1 3 5 2]
c:bubble_sort
returns [1 2 3 4 5]
#end_method

#begin_method
duplicate 
Returns a new collection object with copies of all the elements. Also see duplicate_shallow.
Ex:
{button}:new:rename(#b1)
a := [{button b1}]
a:duplicate
returns [{button copy_of_b1}]

Note: The button in the new collection is a copy of {button b1}.
#end_method

#begin_method
duplicate_shallow 
Returns a new collection object with the same elements. Also see duplicate.
Ex:
{button}:new:rename(#b1)
a := [{button b1}]
a:duplicate_shallow
returns [{button b1}]

Note: The button in the new collection is the same button as in the original collection.
#end_method

#begin_method
empty 
Removes all the elements of the collection.
Returns self.
Ex:
c := [1 2 3 4]
c:empty
returns []
#end_method

#begin_method
first 
Returns the first element of the collection.
Ex:
c := [10 20 30 40]
c:first
returns 10
#end_method

#begin_method
generic_sort(message) 
Sorts the collection and uses message to compare the elements. Using this method you can write your own specialized sorting. The comparing method should take one argument and return true or false.
Returns self.
Ex:
c := [4 1 3 2]
c:generic_sort(#is_less_than)
returns [1 2 3 4]
c:generic_sort(#is_greater_than)
returns [4 3 2 1]
#end_method

#begin_method
includes(element) 
Returns true if element is included in the collection. Otherwise the method returns false.
Ex:
c := [1 2 3 4]
c:includes(5)
returns false
c:includes(2)
returns true
#end_method

#begin_method
index_of(element) 
Returns the index of the first occurrence of element. If there are no occurrences of element the method returns nil.
Note: The first element in a collection has the index 1.
Ex:
c := [4 3 2 1]
c:index_of(1)
returns 4
c:index_of(5)
returns nil
#end_method

#begin_method
insert(element, index) 
Inserts element at index in the collection. If index is higher than the number of elements in the collection the method returns nil.
Returns self.
Note: The first element in a collection has the index 1.
Ex:
c := [1 2 3 4]
c:insert(100, 2)
returns [1 100 2 3 4]
c:insert(100, 6)
returns nil
#end_method

#begin_method
inspect 
Opens the collection inspector for the collection.
Returns self.
#end_method

#begin_method
is_empty 
Returns true if the collection is empty. Otherwise the method returns false.
Ex:
c := [1]
c:is_empty
returns false
c:remove_last
c:is_empty
returns true
#end_method

#begin_method
is_equal_to(object) 
Returns true if all the elements of the collection are equal to the corresponding element in object. Otherwise the method returns false.
Ex:
a := [1 2 3 4]
b := [1 2 3 4]
c := [1 2 4 3]
a:is_equal_to(b)
returns true
a:is_equal_to(c)
returns false
Note: These are equivalent to a = b and a = c.
#end_method

#begin_method
last 
Returns the last element of the collection.
Ex:
c := [10 20 30 40]
c:last
returns 40
#end_method

#begin_method
max 
Returns the element in the collection with the highest value.
Note: The elements should all be of the same type, for example numbers or strings or characters.
Ex:
a := [2 5 3 6]
b := ["one" "two" "three"]
a:max
returns 6
b:max
returns "two"
#end_method

#begin_method
min 
Returns the element in the collection with the lowest value.
Note: The elements should all be of the same type, for example numbers or strings or characters.
Ex:
a := [2 5 3 6]
b := ["one" "two" "three"]
a:min
returns 2
b:min
returns "one"
#end_method

#begin_method
quick_sort 
Sorts the collection using the quick-sort algorithm. 
(Quick-sort is much faster than bubble-sort. Quick-sort is not that fast when the collection is almost sorted from the start.) 
Returns self.
Note: The elements should all be of the same type, for example numbers or strings or characters.
Ex:
c := [4 1 3 5 2]
c:quick_sort
returns [1 2 3 4 5]
#end_method

#begin_method
remove_at(index) 
Removes the element at index. If index is higher than the number of elements in the collection the method returns nil.
Returns self.
Ex:
c := [1 2 3 4]
c:remove_at(3)
returns [1 2 4]
c:remove_at(5)
returns nil
#end_method

#begin_method
remove_duplicates 
Removes all duplicate occurrences of elements in the collection.
Returns self.
Ex:
c := [1 1 2 3 3 4]
c:remove_duplicates
returns [1 2 3 4]
#end_method

#begin_method
remove_first 
Removes the first element in the collection.
Returns the removed element.
Ex:
c := [10 20 30 40]
c:remove_first
returns 10
#end_method

#begin_method
remove_last 
Removes the last element in the collection.
Returns the removed element.
Ex:
c := [10 20 30 40]
c:remove_last
returns 40
#end_method

#begin_method
rename(name) 
Sets the name of the collection object to the symbol name.
Ex:
c := [10 20 30 40]
c:rename(#my_collection)
The collection c can now also be referred to as
{collection my_collection}
and returns [10 20 30 40]
#end_method

#begin_method
replace(old_element, new_element) 
Replaces the first occurrence of old_element with new_element. If there are no occurrences of old_element the method returns nil.
Returns self.
Ex:
c := [1 2 3 1 2 3]
c:replace(1, 100)
returns [100 2 3 1 2 3]
c:replace(4, 100)
returns nil
#end_method

#begin_method
replace_all(old_element, new_element) 
Replaces all occurrences of old_element with new_element. If there are no occurrences of old_element the method returns nil.
Returns the number of replaced elements.
Ex:
c := [1 2 3 1 2 3]
c:replace_all(1, 100)
returns 2
c:replace_all(4, 100)
returns 0
#end_method

#begin_method
replace_at(index, new_element) 
Replaces the element at index with new_element. If index is higher than the number of elements in the collection the method returns nil.
Returns the replaced element.
Ex:
c := [1 2 3 1 2 3]
c:replace_at(4, 100)
returns 1
c:replace_at(8, 100)
returns nil
#end_method

#begin_method
reverse 
Reverses the order of the elements in the collection.
Returns self.
Ex:
c := [1 2 3 4]
c:reverse
returns [4 3 2 1]
#end_method

#begin_method
size 
Returns the number of elements in the collection.
Ex:
c := [10 20 30 40]
c:size
returns 4
#end_method

#begin_method
sort 
Sorts the collection. 
Returns self.
Note: The elements should all be of the same type, for example numbers or strings or characters.
Ex:
c := [4 1 3 5 2]
c:sort
returns [1 2 3 4 5]
#end_method

#begin_method
summate 
Returns the sum of all the elements in the collection.
Note: The elements in the collection must be numbers.
Ex:
c := [1 2 3 4]
c:summate
returns 10
#end_method

Class Methods